Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceltrack/3.0/parcels/
Production:
https://api.nzpost.co.nz/parceltrack/3.0/parcels/
Resource Description
Query to return tracking information for a specific tracking reference.
| Attribute | Detail |
|---|
| Response Format | JSON |
| Requires Authentication | Yes |
| Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Request Message Fields
| Field | Description | Mand | Example |
|---|
| tracking_reference | The unique parcel identifier | Yes | JP100000271NZ |
Sample Request
https://api.nzpost.co.nz/parceltrack/3.0/parcels/JP100000271NZ
Response Parameters
| Field Name | Description | Mand | Example |
|---|
| success | Returns if request is successful | Yes | True |
| results | JSON object containing the parcel and event detail | No | JSON object |
Results Response Elements
| Field Name | Description | Mand | Example |
|---|
| tracking_reference | Tracking Number returned | Yes | JP100000271NZ |
| message_id | Unique identifier for the message | Yes | 46384aa1-54ae-4097-9f59-b321a80e7c0e |
| message_datetime | Date and time stamp on the message | Yes | 2015-10-08T12:12:54.0000000Z |
| service | Delivery service if known | No | Overnight |
| carrier | Carrier code for the parcel | Yes | CourierPost |
| tracking_events | This may be present when the success flag is true. This may be absent if the parcel has no associated scan events at the time of the request or the success flag is false. | No | See Tracking Events Response Elements |
Tracking Events Response Elements
| Element | Description | Mand | Example |
|---|
| tracking_reference | Tracking Number returned | Yes | 00393311680005810444 |
| event_edifact_code | EDIFACT code for the parcel delivery step | Yes | 13 |
| source | Source system where event occurred. Valid systems are: CME, Navigator, IPS, ParcelStore, PSG | No | CME |
| seqref | NZ Post internal system reference number | No | 2631897613 |
| status_description | Brief description the event | String | "Out for Delivery" |
| event_description | Detailed description of the event | String | "Your item is currently with our courier for delivery." |
| event_datetime | This is the time the courier recorded the scan or event. This is the time you should display to your customers | Datetime | 2015-02-04T15:17:03 |
| signed_by | If the item was signature required then the NAME of the signer is shown here | String | See Signed By Response Elements |
| est_delivery_window_start | This is the start time for the delivery window of a parcel.It is triggered by the Out for Delivery event. | Datetime | 08:45:00 |
| est_delivery_window_end | This is the end time for the delivery window of a parcel. It is triggered by the Out for Delivery event. | Datetime | 12:45:00 |
Signed By Response Elements
| Element | Description | Value | Example |
|---|
| name | Full name of the person providing the signature. | Yes if signature required | Lee Child |
| signature | String representation of binary data. | No | ec608f40-2a8b-11e5... |
Scan Reason Response Elements
| Element | Description | Value | Example |
|---|
| reason_code | Number indicating reason for scan type | Mand if scan response present | 2 |
| reason_comment1 | Description corresponding to reason_code | Mand if scan response present | RuralPost |
Error Response Elements
| Field Name | Description | Mand | Example |
|---|
| success | Returns if request is successful | Yes | True |
| errors | Error object with error details | Y if success =false | See Error Object Parameters below |
| message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
| Field Name | Description | Example |
|---|
| code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
| message | Description of error code | Invalid Parameter(s) |
| details | Description of specific error | Unauthorised access, please contact administrator |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
| Code | Message |
|---|
| 200 | Success |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 409 | Invalid request |
| 500 | System unavailable |
Error Codes
| Code | Message |
|---|
| 200001 | Partial results returned, not all system(s) have responded |
| 200002 | All sources responded, data may be incomplete |
| 400001 | Parameter(s) missing |
| 400002 | Invalid parameter(s) |
| 400003 | Non mutually exclusive parameters detected |
| 401001 | Unauthorised access, please contact administrator |
| 500001 | General Exception |
| 500002 | System(s) offline |
Sample Response
Sample:
{
"tracking_reference": "00894210379306766768",
"source": "CME",
"seqref": "7061187316",
"status_description": "With courier for delivery",
"event_description": "Your item is with our courier for delivery. It should be with you today",
"pbu": "082392",
"event_datetime": "2024-06-07T08:33:32",
"signed_by": {
"name": "",
"signature": ""
},
"event_edifact_code": "32",
"est_delivery_window_start": "08:45:00",
"est_delivery_window_end": "12:45:00"
}